Printing Documents Using QuickDraw GX(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / Using Core Printing Features

Printing Documents Using QuickDraw GX
There are two approaches you can take to printing a document depending on how you store data. You can either print each page as a single picture shape or print each page by allowing QuickDraw GX to capture multiple shapes. In the later case, you specify when to start and stop capturing shapes that appear on the page.
If your application stores each page as a single picture shape, you should use the GXPrintPage function to print each page in a document. In the GXPrintPage function, you need to provide QuickDraw GX with the picture shape for each page. A picture shape is a container for other shapes--including other picture shapes, allowing you to create hierarchies of shapes. Picture shapes are discussed in Inside Macintosh: GX Graphics.
You may also choose to use the GXStartPage, GXDrawShape, and GXFinishPage functions to draw and print data. You should use these functions if your application does not store each page as a single picture shape. QuickDraw GX allows you to print in a way similar to how you draw to the screen except that QuickDraw GX captures shapes to send to a print file, such as a spool file or a portable digital document, instead of to a monitor. The GXDrawShape function is described in Inside Macintosh: GX Objects.

IMPORTANT
Some QuickDraw GX functions begin with the word Start or Finish. You must call the corresponding "finish" call only if the "start" call succeeds. For example, after you call the GXStartPage function, you should immediately check for errors. You should call the GXFinishPage function only if GXStartPage did not return an error.
Regardless of whether you print pages as single picture shapes or print pages by capturing shapes, the basic flow of control is as follows:

After the user requests printing, you call the GXGetJobPageRange function to obtain the user-specified page range.
You use the GXStartJob function to begin printing a document with parameters that specify the job object and the name of the user's document. You may also specify the total number of pages the user chose to print or pass 0 if the page count is unknown. In response to the GXStartJob call, QuickDraw GX displays the Status dialog box, which contains the current page number and the total page count, if it is not 0.
After you finish printing, by either method, you call the GXFinishJob function to tell QuickDraw GX that the document is ready to be queued for printing in the background. Note that you should only call the GXFinishJob function if the GXStartJob function doesn't return an error.

Printing Pages as Single Picture Shapes
This section describes how to use the GXPrintPage function to print a user's document. To use this function, you specify the page to print in the pageNumber parameter. QuickDraw GX compares the specified page number with the page range chosen by the user and spools the page if it is within the page range. If it is not within range, the page is ignored.
You should loop through each page of a document, calling the GXPrintPage function for each page's picture shape. You should check for errors after you print each page and exit the loop if an error arises.
Listing 2-5 gives an example of how to use the GXPrintPage function to print a document. In the example, only the default format is used to format each page. To obtain this format, you call the GXGetJobFormat function with an index of 1.
Listing 2-5 Using the GXPrintPage function to print a document
OSErr MyPrintDocument2(MyDocumentPtr myDocument)
{
   OSErr err;
   long  firstPage, lastPage, numPages, pg;
   
   /* Determine which pages the user selected to print. */ 
   GXGetJobPageRange(myDocument->documentJob,
                                          &firstPage,&lastPage);
   if (lastPage > myDocument->numPages)
      lastPage = myDocument->numPages;

   /*
      Calculate the total number of pages to print.  If there are
      no errors, begin printing.
   */
   numPages = lastPage - firstPage + 1;
   err = GXGetJobError(myDocument->documentJob);
   if (err == noErr)
   {
      GXStartJob(myDocument->documentJob,
                           myDocument->documentTitle, numPages);
      err = GXGetJobError(myDocument->documentJob);

      /*
         Loop through each page. Call the GXPrintPage function for
         each page's picture shape.  In this example, we use the
         job's default format to print each page.
      */
      if (err == noErr)
      {
         for (pg = firstPage; (err == noErr) && (pg <= lastPage);
                                                            pg++)
         {
            GXPrintPage(myDocument->documentJob, pg,
                     GXGetJobFormat(myDocument->documentJob, 1),
                     myDocument->documentPage[pg -1]);
            err = GXGetJobError(myDocument->documentJob);
         }

         /* Finish printing. */
         if (err == noErr)
         {
            GXFinishJob(myDocument->documentJob);
            err = GXGetJobError(myDocument->documentJob);
         }
      }
   }
   return err;
}
Printing Pages by Capturing Shapes
This section describes how to use the GXStartPage, GXDrawShape, and GXFinishPage functions to print pages in your application's documents. You use the GXStartPage function to tell QuickDraw GX to capture shapes that you draw using the GXDrawShape function. You call GXFinishPage when you are finished creating the page of output.
In the GXStartPage function, you set the page to print in the pageNumber parameter. QuickDraw GX compares the specified page number with the page range chosen by the user and spools the page if it is within the page range. If it is not within range, the page is ignored.
In the GXStartPage function, you also specify a viewPortList parameter, which is the list of view ports to use to capture shapes. The part of the shape that can be drawn through the view port is spooled. In the numViewPorts parameter, you specify the number of view ports to use (as specified in the viewPortList parameter). QuickDraw GX drawing functions and view port objects are described in Inside Macintosh: GX Objects.

Note
QuickDraw GX does not use the information in a view port, such as its mapping or clipping properties. It uses a view port only to capture the shape information, such as the geometry and color, as shapes are drawn. For example, you can print as you draw by specifying view ports in the onscreen view group in the call to GXStartPage, or you can draw to offscreen view ports to capture shapes without displaying them. In either case, only the information about the shape is spooled.
Listing 2-6 gives an example of how to print a document using the GXStartPage, GXDrawShape, and GXFinishPage functions.
Listing 2-6 Using the GXStartPage, GXDrawShape, and GXFinishPage functions to print a document
OSErr MyPrintDocument2(MyDocumentPtr myDocument)
{
   OSErr    err;
   long     firstPage, lastPage, numPages, pg;
   
   /* Determine which pages the user selected to print. */
   GXGetJobPageRange(myDocument->documentJob, &firstPage, 
                     &lastPage);
   if (lastPage > myDocument->numPages)
      lastPage = myDocument->numPages;

   /* Calculate the total number of pages to print.*/
   numPages = lastPage - firstPage + 1;
   err = GXGetJobError(myDocument->documentJob);

   /* Begin printing if there are no errors. */
   if (err == noErr)
   {
      GXStartJob(myDocument->documentJob, 
                  myDocument->documentTitle, numPages);

      /*
         For each page, call the GXStartPage function, draw the
         page, and then call the GXFinishPage function. In this
         example, the default format and the document's view
         port are used, drawing only a single shape on each page.
      */
      for (pg = firstPage; (err == noErr) && (pg <= lastPage); 
            pg++)
      {

         /* Start the page. */
         GXStartPage(myDocument->documentJob, pg, 
                     GXGetJobFormat(myDocument->documentJob, 1),
                     1, &myDocument->documentViewPort);
         err = GXGetJobError(myDocument->documentJob);
         
         /* If there are no errors, draw the data for the page. */
         if (err == noErr)
         {
            GXDrawShape(myDocument->documentPage[pg -1]);
            err = (OSErr) GXGetGraphicsError(nil);
         }
         if (err == noErr)
            GXFinishPage(myDocument->documentJob);
      }

      /* Finish printing. */
      GXFinishJob(myDocument->documentJob);
      err = GXGetJobError(myDocument->documentJob);
   }
   return err;
}